---
type: engineering-note
title: Domain Modeling
description: Actively sharpen the system's domain model — in this vault, the model IS the Glossary, the enums and the actors.
tags: [engineering, skill]
timestamp: {{DATE}}
---
<!-- ✂ docujoint template sample — replace with your own content, then delete this comment. -->
# Domain Modeling

_Adapted for this knowledge base from
[Matt Pocock's engineering skills](https://github.com/mattpocock/skills/tree/main/skills/engineering)._

## When to use
Any time a conversation, spec or diff uses a domain word loosely — or two
words for one thing, or one word for two things.

## The discipline
1. **The model lives in documents, not heads.** The domain model of this
   system is the [Glossary](</Conventions/Glossary.md>), the enums under
   `Data/*/Enums/`, and the `Actors/`. If a concept isn't there, it isn't
   modelled yet.
2. **New term → Glossary first.** Before code uses a new domain word, add it
   to the Glossary with one meaning. If you can't write one sentence for it,
   you don't understand it yet — that's the finding.
3. **New state → enum document first.** A new status value is a domain event:
   edit the enum doc (e.g. [order-status](</Data/main/Enums/order-status.md>)),
   let lint catch every flow that now needs updating.
4. **Ambiguity → open question, not a guess.** When two people mean different
   things by the same word, record it as an open question on the concept —
   with `About` pointing at the exact row it blocks.

## Signals you skipped this
Synonyms drifting across documents; enum values in code with no enum doc;
flows that say "the order is done" instead of naming a status value.

## Open questions